% -----------------------------------------------------------------------------
%
% Copyright (c) 2017 Sam Cox, Roberto Sommariva
%
% This file is part of the AtChem2 software package.
%
% This file is covered by the MIT license which can be found in the file
% LICENSE.md at the top level of the AtChem2 distribution.
%
% -----------------------------------------------------------------------------

\chapter{Model Installation} \label{ch:installation}

% -------------------------------------------------------------------- %
\section{Requirements} \label{sec:requirements}

AtChem2 can be installed and used on either Linux/Unix or macOS
operating systems. A working knowledge of the \textbf{unix shell} and
its \href{https://swcarpentry.github.io/shell-novice}{basic commands}
is \emph{required} to install and use the model. AtChem2 requires the
following software tools:

\begin{itemize}
\item a terminal with bash or a bash-compatible shell (e.g., zsh is
  the default shell in macOS), and common utilities: wget, tar, zip,
  make, etc\ldots
\item a text editor: Emacs, vim, Gedit, Kate, TextEdit, Atom,
  etc\ldots
\item a Fortran compiler -- the model compiles with GNU
  \texttt{gfortran} (version 4.8 and later) and with Intel
  \texttt{ifort} (version 17.0 and later).\\
  The default Fortran compiler is \texttt{gfortran}.
\item Python~\footnote{All Python scripts used in AtChem2 work equally
    with Python v2 and v3. Support for Python v2 will be removed in
    future versions of AtChem2.}.
\item Ruby version 3.0 or earlier (optional).
\end{itemize}

Some or all of these tools may already be installed on the operating
system: use the \texttt{which} command to find out (e.g.,
\verb|which python|, \verb|which make|, etc\ldots). Otherwise, check
the local documentation or ask the system administrator. In addition,
AtChem2 has the following dependencies:

\begin{itemize}
\item CVODE -- requires gcc, cmake %BLAS, LAPACK
\item openlibm
\item numdiff (optional)
\item FRUIT (optional)
\end{itemize}

For detailed instructions on the installation and configuration of the
dependencies, go to Sect.~\ref{sec:dependencies}. As an alternative,
AtChem2 can be run as a \href{https://www.docker.com}{Docker}
container. For details, go to Sect.~\ref{sec:docker}.

% -------------------------------------------------------------------- %
\section{Download} \label{sec:download}

The primary repository for the AtChem2 code and documentation is:\\
\href{https://github.com/AtChem/AtChem2}{https://github.com/AtChem/AtChem2}.

Two versions of the model are available: the \emph{stable version} and the
\emph{development version} -- i.e. the \texttt{master\ branch} of the git
repository, see Sect.~\ref{sec:general-information}. Although the two
versions are usually equivalent, it is recommended to use the stable
version which can be easily referenced in publications using the version
and \href{https://www.doi.org/the-identifier/what-is-a-doi}{doi} numbers.
The AtChem2 source code can be obtained in two ways:

\begin{enumerate}
\item with \textbf{git} (this is the best method for users who want to
  contribute to the model development, Sect.~\ref{ch:development}):
  \begin{itemize}
  \item Open the terminal. Move to the directory where AtChem2 will be
    installed.
  \item Execute one of the following commands to copy the
    \texttt{master\ branch} to the local machine:
    \begin{itemize}
      \item if using HTTPS:\\
        \verb|git clone https://github.com/AtChem/AtChem2.git|
      \item if using SSH:\\
        \verb|git clone git@github.com:AtChem/AtChem2.git|
    \end{itemize}
  \end{itemize}
\item with the \textbf{archive file}:
  \begin{itemize}
  \item Download the archive file (\texttt{.tar.gz} or \texttt{.zip}) of
    the \href{https://github.com/AtChem/AtChem2/releases}{stable} or the
    \href{https://github.com/AtChem/AtChem2/archive/master.zip}{development}
    version to the directory where AtChem2 will be installed.
  \item Open the terminal. Move to the directory where the archive
    file was downloaded.
  \item Execute \verb|tar -zxfv *.tar.gz| or \verb|unzip -v *.zip|
    (depending on which file was downloaded) to unpack the archive
    file.
  \end{itemize}
\end{enumerate}

The AtChem2 source code is now in a directory called \texttt{AtChem2}
(if git was used) or \texttt{AtChem2-1.x} (if the archive file of the
stable version was downloaded) or \texttt{AtChem2-master} (if the
archive file of the development version was downloaded). This
directory is the AtChem2 \maindir. In this manual, the \maindir\ is
assumed to be \texttt{\$HOME/AtChem2/}, but it can be given any name
and path -- depending on the user's preferences.

% -------------------------------------------------------------------- %
\section{Dependencies} \label{sec:dependencies}

AtChem2 has a number of dependencies (additional software tools and
libraries): some are \emph{required}, and without them the model
cannot be installed or used, others are \emph{optional}, and only
needed to run the Testsuite (Sect.~\ref{sec:test-suite}).

It is recommended to install all the dependencies into the same
directory, called \depdir. In this manual, the \depdir\ is assumed to
be \texttt{\$HOME/AtChem-lib/}, but it can be given any name and path
-- depending on the user's preferences.

Before installing the dependencies, make sure that the requirements
listed in Sect.~\ref{sec:requirements} are met, and that the unix
shell is bash or bash-compatible (type \verb|echo $SHELL| at the
terminal to check the shell type).

\subsection{Required dependencies} \label{subsec:required-dependencies}

% \subsubsection{BLAS and LAPACK}

% BLAS and LAPACK are standard Fortran libraries for linear
% algebra. Together with \texttt{cmake} hey are needed only to compile
% the CVODE library -- see below. Usually they are located in the
% \texttt{/usr/lib/} directory (e.g., \texttt{/usr/lib/libblas/} and
% \texttt{/usr/lib/lapack/}). The location may be different,
% especially on a High Performance Computing (HPC) system: check the
% local documentation or ask the system administrator.

\subsubsection{CVODE}

AtChem2 uses the CVODE library, which is part of the open source
\href{https://computing.llnl.gov/projects/sundials}{SUNDIALS suite}
\citep{hindmarsh_2005}, to solve the system of ordinary differential
equations (ODE). The version of CVODE currently used in AtChem2 is
v2.9.0 (part of SUNDIALS v2.7.0) and it can be installed using the
script \texttt{install\_cvode.sh} in the \texttt{tools/install/}
directory.

\begin{enumerate}
\item Open the terminal. Move to the \maindir\ (\verb|cd ~/AtChem2/|).
\item Open the installation script (\texttt{tools/install/install\_cvode.sh})
  with the text editor:
  \begin{itemize}
  % \item If LAPACK and BLAS are not in the default location (see
  %   above), change the \texttt{LAPACK\_LIBS} variable for your
  %   architecture (Linux or macOS) as appropriate.
  \item If using a compiler other than \texttt{gcc}, change the line:\\
    \texttt{-DCMAKE\_C\_COMPILER:FILEPATH=gcc \textbackslash}
  \end{itemize}
\item Run the installation script (change the path to the \depdir\ as needed):
  \begin{verbatim}
  ./tools/install/install_cvode.sh ~/AtChem-lib/
  \end{verbatim}
\end{enumerate}

If the installation is successful, there is now a working CVODE installation
at \texttt{\textasciitilde/AtChem-lib/cvode/}. Take note of the CVODE library
path (\texttt{\textasciitilde/AtChem-lib/cvode/lib/}), as it will be
needed later to complete the configuration of AtChem2 (Sect.~\ref{sec:install}).

\subsubsection{openlibm}

openlibm is a portable implementation of the open source mathematical
library \href{https://openlibm.org}{libm}. Installing openlibm and
linking against it, allows reproducible results by ensuring the same
implementation of several mathematical functions across platforms.

The current version of openlibm is 0.8.1 and it can be installed using
the script \texttt{install\_openlibm.sh} in the \texttt{tools/install/}
directory.

\begin{enumerate}
\item Open the terminal. Move to the \maindir\ (\verb|cd ~/AtChem2/|).
\item Run the installation script (change the path to the \depdir\ as needed):
  \begin{verbatim}
  ./tools/install/install_openlibm.sh ~/AtChem-lib/
  \end{verbatim}
\end{enumerate}

\emph{Warning}: the compilation of openlibm on \textbf{macOS} may fail
with a message concerning the \texttt{dyld} library. This is analogous
to the error that may occur the first time that AtChem2 is run on
macOS (see below, in Sect.~\ref{sec:install}) and can be resolved in a
similar way.

If the installation is successful, there is now a working openlibm
installation at \texttt{\textasciitilde/AtChem-lib/openlibm-0.8.1/}.
Take note of the openlibm library path, as it will be needed later to
complete the configuration of AtChem2 (Sect.~\ref{sec:install}).

\subsection{Optional dependencies} \label{subsec:optional-dependencies}

\subsubsection{numdiff}

numdiff is an open source \href{https://www.nongnu.org/numdiff}{tool}
to compare text files containing numerical fields. It is needed only
to run the \hyperref[sec:test-suite]{Testsuite}, a battery of tests
used during the development of AtChem2 to ensure that the model works
properly and that changes to the source code do not result in
unintended behaviour. Installation of numdiff is recommended for users
who want to contribute to the development of AtChem2, but otherwise
optional.

Use \verb|which numdiff| to check if the program is already installed
on the operating system. If not, ask the system administrator.
Alternatively, numdiff can be installed locally (e.g., in the \depdir)
using the script \texttt{install\_numdiff.sh} in the
\texttt{tools/install/} directory.

\begin{enumerate}
\item Open the terminal. Move to the \maindir\ (\verb|cd ~/AtChem2/|).
\item Run the installation script (change the path to the \depdir\ as
  needed):
  \begin{verbatim}
  ./tools/install/install_numdiff.sh ~/AtChem-lib/
  \end{verbatim}
\item Move to the \texttt{\$HOME} directory (\texttt{cd\ \textasciitilde}).
  Open the \texttt{.bash\_profile} file (or the \texttt{.profile}
  file, depending on the system configuration) with a text editor. Add the
  following line to the bottom of the file (change the path to the
  \depdir\ as needed):
  \begin{verbatim}
  export PATH=$PATH:$HOME/AtChem-lib/numdiff/bin
  \end{verbatim}
\item Close the terminal.
\item Reopen the terminal. Execute \verb|which numdiff| to check that
  the program has been installed correctly.
\end{enumerate}

\subsubsection{FRUIT}

FRUIT (FORTRAN Unit Test Framework) is an open source testing library
for Fortran. It requires Ruby~\footnote{The current version of FRUIT
  does not compile with Ruby v3.2 due to some deprecated
  syntax. Version 3.0 or earlier must be used until the FRUIT
  developers release an update.} and it is needed only to run the unit
tests (Sect.~\ref{sec:test-suite}). Installation of FRUIT is
recommended for users who want to contribute to the development of
AtChem2.

The current version of FRUIT is 3.4.3 and it can be installed using
the script \texttt{install\_fruit.sh} in the \texttt{tools/install/}
directory.

\begin{enumerate}
\item Open the terminal. Move to the \texttt{\$HOME} directory
  (\texttt{cd\ \textasciitilde}). Open the \texttt{.bash\_profile}
  file (or the \texttt{.profile} file, depending on the system
  configuration) with a text editor. Add the following lines to the
  bottom of the file:
  \begin{verbatim}
  export GEM_HOME=$HOME/.gem
  export PATH=$PATH:$GEM_HOME/bin
  \end{verbatim}
\item Close the terminal.
\item Reopen the terminal. Move to the \maindir\ (\verb|cd ~/AtChem2/|).
\item Run the installation script (change the path to the \depdir\ as
  needed):
  \begin{verbatim}
  ./tools/install/install_fruit.sh ~/AtChem-lib/
  \end{verbatim}
\end{enumerate}

If the installation is successful, there is now a working FRUIT
installation at \texttt{\textasciitilde/AtChem-lib/fruit\_3.4.3/}.
Take note of the FRUIT library path, as it will be needed later to
complete the configuration of AtChem2 (Sect.~\ref{sec:install}).


% -------------------------------------------------------------------- %
\section{Install} \label{sec:install}

To install AtChem2:

\begin{enumerate}
\item Open the terminal. Move to the \maindir\ (\verb|cd ~/AtChem2/|).
  Install the \hyperref[sec:dependencies]{Dependencies} and take note
  of the names and paths of CVODE, openlibm and (if installed) FRUIT.
\item Copy the example \texttt{Makefile} from the \texttt{tools/install/}
  directory to the \maindir:
  \begin{verbatim}
  cp ./tools/install/Makefile.skel ./Makefile
  \end{verbatim}
\item Open the \texttt{Makefile} with a text editor. Set the variables
  \texttt{\$CVODELIBDIR}, \texttt{\$OPENLIBMDIR}, \texttt{\$FRUITDIR}
  to the paths of CVODE, openlibm and FRUIT, as indicated in
  Sect.~\ref{subsec:required-dependencies}. Use \emph{full paths},
  because relative paths may cause compilation errors~\footnote{See
    issue \href{https://github.com/AtChem/AtChem2/issues/364}{\#364}.}.
  For example (change the path to the \depdir\ as needed):
  \begin{verbatim}
  CVODELIBDIR = $(HOME)/AtChem-lib/cvode/lib
  OPENLIBMDIR = $(HOME)/AtChem-lib/openlibm-0.8.1
  FRUITDIR = $(HOME)/AtChem-lib/fruit_3.4.3
  \end{verbatim}
  If FRUIT has not been installed (it is optional and needed only to
  run certain tests), leave the default value for \texttt{\$FRUITDIR}.
\item Compile AtChem2 with the \texttt{build\_atchem2.sh} script in
  the \texttt{build/} directory:
  \begin{verbatim}
  ./build/build_atchem2.sh ./model/mechanism.fac
  \end{verbatim}
  This command creates an executable (called \texttt{atchem2}) using
  the example mechanism file \texttt{mechanism.fac} in the
  \texttt{model/} directory.
\item Execute \verb|./atchem2| from the \maindir. The command runs the
  model executable using the default chemical mechanism and settings,
  which are in the \texttt{model/} directory. The executable prints
  information to the terminal while it is running, such as the
  model settings, warning messages (if any), and timesteps. If the
  model run completes successfully, the terminal will display a
  message like this:
  \begin{verbatim}
  ------------------
   Final statistics
  ------------------
   No. steps = 546   No. f-s = 584   No. J-s = 912   No. LU-s = 56
   No. nonlinear iterations = 581
   No. nonlinear convergence failures = 0
   No. error test failures = 4

   Runtime = 0
   Deallocating memory.
  \end{verbatim}
\end{enumerate}

\emph{Warning}: when AtChem2 is run for the first time on a
\textbf{macOS} system, it may abort with the following message:

\begin{verbatim}
dyld: Library not loaded: @rpath/libsundials_cvode.2.dylib
\end{verbatim}

This error is related to the path of dynamic libraries on macOS:
to resolve the issue, follow the suggestions on the
\href{https://github.com/AtChem/AtChem2/wiki/Known-Issues}{wiki}.

AtChem2 is now ready to be used. Optionally, the Testsuite can be run
to check the model installation: go to Sect.~\ref{subsec:tests-optional}
for more information. The directory structure of AtChem2 is described
in Sect.~\ref{sec:model-structure} (see also Fig.~\ref{fig:atchem-arch}).
For detailed instructions on how to set up, configure, build and
run an AtChem2 box-model, go to Chapt.~\ref{ch:setup} and
Chapt.~\ref{ch:execution}.

\subsection{Tests (optional)} \label{subsec:tests-optional}

The \hyperref[sec:test-suite]{Testsuite} can be used to verify that
AtChem2 has been installed correctly and works as intended. This step
is not necessary, but it is recommended especially for users who want
to contribute to the development of the AtChem2 model. Note that the
\hyperref[subsec:optional-dependencies]{optional dependencies} have to
be installed to run the Testsuite.

Open the terminal and execute one of the following commands from the
\maindir:

\begin{itemize}
\item \verb|make alltests|: runs all the tests (requires numdiff and FRUIT).
\item \verb|make modeltests|: runs only the Model tests (requires numdiff).
\item \verb|make unittests|: runs only the Unit tests (requires FRUIT).
\end{itemize}

The command runs the requested tests, then prints the tests output and
a summary of the results to the terminal. The logfiles of the test run
can be found in the \texttt{tests/} directory.

% -------------------------------------------------------------------- %
\section{Docker} \label{sec:docker}

As an alternative to the installation of AtChem2 described above, a
containerised version of the model is available. Currently this is
built only for version 1.2.2. The container is built on Rocky Linux 8.9
and pre-installs the CVODE and openlibm dependencies via the corresponding
install scripts (Sect.~\ref{subsec:required-dependencies}).
The image can be downloaded via the command:

\begin{verbatim}
docker pull ghcr.io/wacl-york/atchem2:1.2.2
\end{verbatim}

When running the container, changes to the model (e.g., those made to
configurations, constraints and mechanisms) should be in a folder that
matches the AtChem2 directory structure. This folder is then mounted
as a volume to the container with the name \texttt{/data\_transfer/}.
The chemical mechanism to use is provided as a positional argument to
the image (e.g., \texttt{./model/my\_mech.fac}).

Example host file structure:
\begin{verbatim}
my_model_run
 |__ model
     |__ configuration
     |__ constraints
     |__ my_mech.fac
\end{verbatim}

Example Docker run command:

\begin{verbatim}
docker run -it --rm -v /path/to/my_model_run:/data_transfer
       ghcr.io/wacl-york/atchem2:1.2.2 ./model/my_mech.fac
\end{verbatim}

Outputs will be copied to \texttt{my\_model\_run/model/output} on completion.

Running on Singularity / Apptainer

Some HPC systems use Singularity / Apptainer instead of Docker as
their container engine. This image is compatible with those
as well. The image can be converted to a \texttt{.sif} via the command:

\begin{verbatim}
apptainer pull path/to/image/atchem2.sif
          docker://ghcr.io/wacl-york/atchem2:1.2.2
\end{verbatim}

Example Apptainer run command:

\begin{verbatim}
apptainer run --bind /path/to/my_model_run/:/data_transfer/
          path/to/image/atchem2.sif ./model/my_mech.fac
\end{verbatim}

Note that the leading \texttt{/} is important when mounting the volume
for apptainer, as the container opens in the users \texttt{~}
directory whereas Docker opens at \texttt{/}.

% -------------------------------------------------------------------- %
\section{Model Structure} \label{sec:model-structure}

AtChem2 is organized in several directories which contain the source
code, the compilation files, the chemical mechanism, the model
configuration and output, several scripts and utilities, and the Testsuite.

The directory structure of AtChem2 is derived from the directory
structure of AtChem-online, but it was substantially changed with the
release of version 1.1 (November 2018). Tab.~\ref{tab:atchem-dirs}
shows the new directory structure and, for reference, the original
one.

\begin{table}[htb]
  \centering \scriptsize
  \caption{Directory structure of AtChem2.\\
    $(\dag)$ Not present in AtChem-online $(\ddag)$ Since version 1.2.2}
  \label{tab:atchem-dirs}
  \begin{tabular}{llp{3.9cm}}
    Version 1.0 and earlier & Version 1.1 and later & Description\\
    \hline
    --                               & \texttt{build/}                         & scripts to build the model\\
    \hline
    --                               & \texttt{doc/}                           & user manual and other documents\\
    \hline
    --                               & \texttt{docker/}~$(\ddag)$              & Docker-related files\\
    \hline
    --                               & \texttt{mcm/}                           & MCM data files and example mechanism files\\
    \hline
    \texttt{modelConfiguration/}     & \texttt{model/configuration/}           & chemical mechanism, shared library, model and solver configuration files\\
    \hline
    \texttt{speciesConstraints/}     & \texttt{model/constraints/species/}     & model constraint files: chemical species\\
    \hline
    \texttt{environmentConstraints/} & \texttt{model/constraints/environment/} & model constraint files: environment variables\\
    \hline
    \texttt{environmentConstraints/} & \texttt{model/constraints/photolysis/}  & model constraint files: photolysis rates, JFAC\\
    \hline
    \texttt{modelOutput/}            & \texttt{model/output/}                  & model results: chemical species, environment variables, photolysis rates, production/loss rates of selected species, diagnostic variables\\
    \hline
    \texttt{instantaneousRates/}     & \texttt{model/output/reactionRates/}    & model results: reaction rates of every reaction in the chemical mechanism\\
    \hline
    \texttt{obj/}                    & \texttt{obj/}                           & module and object files generated by the Fortran compiler\\
    \hline
    \texttt{src/}                    & \texttt{src/}                           & Fortran source files\\
    \hline
    \texttt{travis/}~$(\dag)$        & \texttt{tests/}~$(\ddag)$               & Testsuite scripts, logs and files\\
    \hline
    \texttt{tools/}                  & \texttt{tools/}                         & installation scripts, plotting tools and other utilities\\
  \end{tabular}
\end{table}

In AtChem2 v1.1 (and later versions) the directories \texttt{build/},
\texttt{mcm/}, \texttt{obj/} and \texttt{src/} contain the build
scripts, the MCM data files, the files generated by the Fortran
compiler and the Fortran source code. The directory \texttt{tests/}
contains the files and scripts necessary to run the
\hyperref[sec:test-suite]{Testsuite}; the directory \texttt{docker/}
contains the scripts necessary to run AtChem2 as a Docker container.

For the majority of the users, the most important directories are
\texttt{doc/} which contains the user manual, \texttt{tools/} which
contains the installation and plotting scripts, and \texttt{model/}
which contains the model configuration, input, output and (usually)
the chemical mechanism. Detailed information on these three
directories are in the following sections.

\subsection{The \texttt{doc/} and \texttt{tools/} directories} \label{subsec:doc-tools-directories}

The \texttt{doc/} directory contains the AtChem2 user manual (this
document, \texttt{AtChem2-Manual.pdf}), along with the corresponding
\LaTeX\ files and figures. An electronic copy of the poster presented
at the 2018 Atmospheric Chemical Mechanisms Conference \citep{sommariva_2018}
is also included (\texttt{AtChem\_poster\_ACM2018.pdf}).

The \texttt{tools/} directory contains the script used to update the version
number of AtChem2 in each \hyperref[ch:development]{development cycle}
(\texttt{update\_version\_number.sh}), two scripts to check the
consistency of the Fortran code (\texttt{fix\_style.py} and
\texttt{fix\_indent.py}, see Sect.~\ref{sec:style-guide}), and the
following subdirectories:

\begin{itemize}
\item \texttt{install/}: contains the example \texttt{Makefile}
  (\texttt{Makefile.skel}) and the scripts to install the
  \hyperref[sec:dependencies]{Dependencies}.
\item \texttt{plot/}: contains basic plotting scripts in various
  programming languages.
\end{itemize}

In earlier versions of AtChem2, the \texttt{tools/} directory also
included the build scripts, which have been moved to the
\texttt{build/} directory with the release of version 1.2.

The plotting scripts in \texttt{tools/plot/} are very simple and
produce identical outputs. They are only intended to give the user a
quick overview of the model results for validation and diagnostic
purposes. It is recommended to use a proper data analysis software
package (e.g., R, Python, Igor, MATLAB, Origin, IDL, etc\ldots) to
process and analyze the model results.

The plotting scripts are written in different programming languages:
gnuplot, Octave~\footnote{GNU Octave is an open source implementation
  of MATLAB. The script \texttt{plot-atchem2.m} works with both Octave
  and MATLAB.}, Python, R. One or more of these environments is
probably already installed on the operating system: check the local
documentation or ask the system administrator. All plotting scripts
require one argument -- the path of the directory containing the model
output -- and produce the same output: one file called
\texttt{atchem2\_output.pdf} in the model output directory.

To run a plotting script, open the terminal and execute one of the
following commands from the \maindir\ (change the path to the model
output directory as needed):

\begin{itemize}
\item \verb|gnuplot -c ./tools/plot/plot-atchem2.gp ./model/output/|
\item \verb|octave ./tools/plot/plot-atchem2.m ./model/output/|
\item \verb|python ./tools/plot/plot-atchem2-numpy.py ./model/output/|
\item \verb|python ./tools/plot/plot-atchem2-pandas.py ./model/output/|
\item \verb|Rscript --vanilla ./tools/plot/plot-atchem2.r ./model/output/|
\end{itemize}

\subsection{The \texttt{model/} directory} \label{subsec:model-directory}

The \texttt{model/} directory is the most important from the point of
view of the user. All the information required to set up and run a
box-model with AtChem2, together with the results of the model run, is
contained in this directory.

The \texttt{model/} directory includes the model configuration files,
the model constraints, and the model output. In principle, the
chemical mechanism file (\texttt{.fac}) can be located in any
directory, although it is recommended to keep it in the
\texttt{model/} directory with the rest of the configuration files.

The \texttt{model/} directory can be given any name and can even be
located outside the \maindir. Moreover, there can be multiple
\texttt{model/} directories (with different names) in the same
location. The paths to the required \texttt{model/} directory and/or
chemical mechanism file are given as arguments to the build script
(\texttt{build/build\_atchem2.sh}) and to the \texttt{atchem2}
executable, as explained in Sect.~\ref{sec:build} and
\ref{sec:execute}.

This approach gives the user the flexibility to run different versions
of the same model (in terms of configuration and/or chemical
mechanism) or different models (e.g., for separate projects) at the
same time, without having to recompile the source code and create a
different executable every time. Batch model runs are therefore easy
to do, since all the components of the model that have to be modified
are contained in the same directory. Further information can be found
in Sect.~\ref{subsec:build-process}.\\

\textcolor{red}{\bf Important Note}: whenever the \texttt{model/}
directory is mentioned in this manual, it is implied that its name and
location may be different than the default name (\texttt{model/}) and
location (\maindir). All scripts that require this information, as
well as the \texttt{atchem2} executable, allow the user to specify the
path to the \texttt{model/} directory and to its subdirectories, as
needed.
